break: update kratos modules to v3 by tonybase · Pull Request #3822 · go-kratos/kratos

tonybase · 2026-05-12T15:03:51Z

Description (what this PR does / why we need it):

Update the root module from github.com/go-kratos/kratos/v2 to github.com/go-kratos/kratos/v3.
Update cmd and contrib module paths, imports, docs, and generated references from /v2 to /v3, including cmd/protoc-gen-go-errors/v3.
Update internal module require and replace references to github.com/go-kratos/kratos/v3 v3.0.0.
Update golangci-lint to v2.12.2 and fix new lint findings.

Which issue(s) this PR fixes (resolves / be part of):

Refs #3820.

This PR owns the shared v3 integration branch; follow-up v3 feature PRs should target v3 first.

Other special notes for the reviewers:

Local validation:

make clean
make lint
go build ./...
go test ./...
go test -race ./...
go build ./... in cmd/kratos
go test ./... in cmd/protoc-gen-go-errors
go test ./... in cmd/protoc-gen-go-http

Service-backed contrib tests are covered by GitHub Actions, which starts etcd, Consul, Nacos, and Polaris.

* refactor(log)!: use slog logger facade Replace the legacy Kratos log abstraction with a lightweight slog facade. Move OpenTelemetry log, tracing, and metrics integrations into contrib. Refs #3820 BREAKING CHANGE: The log package now uses *slog.Logger and removes the legacy Logger interface, helper, std logger, value helpers, and core OTEL tracing and metrics middleware. * chore(log): align lint and module versions Keep contrib logging modules on their existing dependency baselines and use Go 1.22-compatible OpenTelemetry bridge versions for contrib/otel. Refs #3820 * fix(log): update polaris error logging Use slog-style Error calls after the log facade refactor. Refs #3820 * feat(log): add WithLogOptions to contrib adapters and otel/log Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(log): add With helper to create logger with pre-attached attributes Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * style(log): fix import ordering in contrib tests Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * refactor: add context to log.Fatal calls for better error diagnostics Replace bare `log.Fatal(err.Error())` with `log.Fatalf()` that includes descriptive context about the failed operation, improving debuggability. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(log): preallocate context attrs * refactor(log): use handler-first logger construction --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Move protobuf JSON handling out of encoding/json so the json codec uses only the Go standard library. Add encoding/protojson for explicit protojson registration and keep gRPC JSON behavior backed by protojson. Part of #3820 BREAKING CHANGE: encoding/json no longer handles protobuf JSON.

Move the JWT middleware into a standalone contrib module so the core module no longer pulls in golang-jwt as a direct dependency. Refs #3820

Remove the exported metadata API package from the core module and stop the gRPC server from registering kratos.api.Metadata by default. BREAKING CHANGE: the github.com/go-kratos/kratos/v3/api/metadata package is no longer provided by the core module. Refs #3820

Move the default circuit breaker, rate limiter, and subset selection into internal packages so the core module no longer imports aegis. Refs #3820

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Replace the default config merge hook with an internal map merge implementation so the core module no longer depends on mergo. Refs #3820

…pdates unconditionally Remove the printDiscoveryDebugLog option from gRPC client and the debugLog field from the discovery builder/resolver. The instance update log in the resolver is now always printed, removing an unnecessary toggle that defaulted to on. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(transport): support http streaming Add protoc-gen-go-http generation for server-streaming SSE and client or bidirectional streaming over WebSocket. Support google.api.HttpBody upload and download paths and select stream codecs from Accept and Content-Type headers. Refs #3820 * fix(ci): resolve http streaming lint failures

Add a contrib JSON codec that preserves the v2 behavior of handling proto.Message values through protojson while keeping the json codec name for migration. Refresh the root English and Chinese READMEs around examples, v3 structure, and migration entry points, and add v2-to-v3 migration guides. Refs #3820

… across codebase Remove all fmt.Sprintf-based log functions (Debugf, Infof, Warnf, Errorf, Fatalf and Context variants) and Fatal functions. Add WithGroup, Handler, and Enabled convenience functions. Use runtime.Callers for correct source attribution instead of delegating directly to slog. Migrate all call sites from printf-style to structured key-value logging. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

shenqidebaozi · 2026-05-20T09:12:36Z

+	opts = append([]http.CallOption{
+		http.Accept("application/protojson"),
+		{{- if not .BodyHTTPBody}}
+		http.ContentType("application/protojson"),
+		{{- end}}
+		http.Operation(Operation{{$svrType}}{{.OriginalName}}),
+		http.PathTemplate(pattern),
+	}, opts...)


Generated HTTP clients default to protojson, but the codec may not be registered

cmd/protoc-gen-go-http/httpTemplate.tpl:260-264 generates clients with Accept("application/protojson") / ContentType("application/protojson"). The
generated file only imports transport/http (internal/testdata/helloworld/helloworld_http.pb.go:7-10), so encoding/protojson is not guaranteed to be
registered.

Then transport/http/client.go:351 and transport/http/codec.go:115-116 call Marshal on encoding.GetCodec(name) without checking nil. If an app only
imports the generated HTTP client/server code and does not separately blank-import github.com/go-kratos/kratos/v3/encoding/protojson, this can pan
ic.

Suggested fix: either blank-import the default codec inside transport/http, or make generated HTTP code blank-import encoding/protojson. Also add
nil checks around GetCodec to return a clear error instead of panicking.

shenqidebaozi · 2026-05-20T09:13:20Z

+	return nil
+}
+
+func (s *websocketClientStream) CloseSend() error {


WebSocket CloseSend does not prevent later Send calls

transport/http/stream.go:403-407 sends the end control frame but does not mark the send side as closed. transport/http/stream.go:433-440 still
allows later SendMsg calls.

That violates gRPC-style stream semantics: after CloseSend, further sends should fail. It can also put the server in an odd state where it has
already observed EOF but the client keeps writing messages.

Suggested fix: track a sendClosed state separately from full stream close, guard it with a mutex or atomic, and make SendMsg return a clear error
after CloseSend. Add a test for CloseSend followed by Send.

I stopped dependency-related test work per your instruction. Static checks plus the tests that did not need those blocked dependencies showed cmd/
protoc-gen-go-http, log, config, and base middleware passing.

shenqidebaozi · 2026-05-20T09:16:40Z

WebSocket stream state handling in transport/http/stream.go
Replace the single unsynchronized closed bool with clearer state:
- sendClosed
- closed
- closeOnce sync.Once
This avoids duplicate close behavior, data races, and makes CloseSend semantics closer to gRPC.
Add nil protection around encoding.GetCodec(...)
Several paths assume codecs always exist. After splitting json and protojson, that assumption is fragile. A small helper like codecOrError(name)
would make failures explicit instead of panicking.
Escape path variables in BuildPath
transport/http/path.go inserts values directly into URL paths. Values containing spaces, ?, #, %, etc. can produce invalid or surprising URLs.
Use url.PathEscape, but handle resource-name templates like {name=publishers//books/} carefully because / may be intentional.
Reduce runtime work in BuildPath
It currently regex-parses templates and encodes all query values at runtime. Since most calls come from generated code, path variable names and
omitted fields could be generated statically to reduce regex/map work. Lower priority, but cleaner and faster.
Avoid the 1 MB SSE event limit
bufio.Scanner in sseClientStream is capped at 1 MB. Large streaming messages will fail. bufio.Reader.ReadString('\n') would be more flexible, or
the size limit should be documented.
Clarify or implement streaming trailers
serverStream.SetTrailer stores trailers, but SSE/WebSocket close paths do not send them. Either implement trailer delivery or document that HTTP
streaming trailers are currently ignored.

Fix variable name from req to v and simplify error handling in the Validator function examples.

break: update kratos modules to v3

2429a52

dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label May 12, 2026

tonybase added the v3 label May 12, 2026

test: use english text in affected tests

c609136

tonybase mentioned this pull request May 12, 2026

[Proposal] Kratos v3: Clean up historical design issues and reduce external dependencies #3820

Open

8 tasks

go-kratos deleted a comment from kratos-ci-bot May 12, 2026

tonybase and others added 4 commits May 13, 2026 00:19

refactor(middleware): move jwt to contrib (#3824)

3bfeb37

Move the JWT middleware into a standalone contrib module so the core module no longer pulls in golang-jwt as a direct dependency. Refs #3820

dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels May 13, 2026

tonybase and others added 4 commits May 13, 2026 23:27

refactor: internalize aegis defaults (#3826)

1be178e

Move the default circuit breaker, rate limiter, and subset selection into internal packages so the core module no longer imports aegis. Refs #3820

refactor(http)!: remove binding package (#3827)

ac849d9

refactor(http): bump SupportPackageIsVersion to version 3

d155d8a

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

refactor(config): remove mergo dependency (#3828)

fdbdbe3

Replace the default config merge hook with an internal map merge implementation so the core module no longer depends on mergo. Refs #3820

tonybase requested a review from shenqidebaozi May 14, 2026 14:00

tonybase and others added 10 commits May 14, 2026 23:24

chore(deps): update Go module dependencies

d5a277d

chore(deps): tidy registry module dependencies

0c41271

chore(deps): tidy mcp module dependency

d5f622f

fix(ci): resolve v3 workflow failures

6beb516

fix(ci): replace deprecated client APIs

2cfe35e

fix(ci): stabilize polaris routing tests

c8b3732

fix(ci): avoid polaris nearby route loading

a9a7745

fix(ci): honor canceled nacos watch context

df4f4a4

tonybase requested review from daemon365 and hawkingrei May 15, 2026 10:01

shenqidebaozi reviewed May 18, 2026

View reviewed changes

Comment thread transport/http/stream.go Outdated

shenqidebaozi reviewed May 18, 2026

View reviewed changes

Comment thread transport/http/stream.go

shenqidebaozi reviewed May 18, 2026

View reviewed changes

Comment thread transport/http/stream.go

fix(transport/http): handle stream client lifecycle

c534665

tonybase force-pushed the v3 branch from e769194 to c534665 Compare May 18, 2026 04:17

shenqidebaozi reviewed May 20, 2026

View reviewed changes

fix(middleware/validate): correct validator example code in doc comment

9030865

Fix variable name from req to v and simplify error handling in the Validator function examples.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

break: update kratos modules to v3#3822

break: update kratos modules to v3#3822
tonybase wants to merge 24 commits into
mainfrom
v3

tonybase commented May 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shenqidebaozi May 20, 2026

Uh oh!

shenqidebaozi May 20, 2026

Uh oh!

shenqidebaozi commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

tonybase commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (what this PR does / why we need it):

Which issue(s) this PR fixes (resolves / be part of):

Other special notes for the reviewers:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shenqidebaozi May 20, 2026

Choose a reason for hiding this comment

Uh oh!

shenqidebaozi May 20, 2026

Choose a reason for hiding this comment

Uh oh!

shenqidebaozi commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tonybase commented May 12, 2026 •

edited

Loading